/*
 * 版权所有 (C) 2015 知启蒙(ZHIQIM) 保留所有权利。[遇见知启蒙，邂逅框架梦]
 * 
 * https://zhiqim.org/project/zhiqim_framework/zhiqim_kernel.htm
 *
 * Zhiqim Kernel is licensed under Mulan PSL v2.
 * You can use this software according to the terms and conditions of the Mulan PSL v2.
 * You may obtain a copy of Mulan PSL v2 at:
 *          http://license.coscl.org.cn/MulanPSL2
 * THIS SOFTWARE IS PROVIDED ON AN "AS IS" BASIS, WITHOUT WARRANTIES OF ANY KIND,
 * EITHER EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO NON-INFRINGEMENT,
 * MERCHANTABILITY OR FIT FOR A PARTICULAR PURPOSE.
 * See the Mulan PSL v2 for more details.
 */
package org.zhiqim.kernel.websocket;

/**
 * WebSocket服务接口定义，三个控制服务和四个消息服务
 * 1、onOpen/onClose/onException控制服务
 * 2、onText/onBinary/onMiddle/onOther消息服务
 *
 * @version v1.5.2 @author zouzhigang 2020-4-26 新建与整理
 */
public interface WebSocketService
{
    /**
     * 连接开启
     * 
     * @param conn      WS连接
     */
    void onOpen(WebSocket conn);
    
    /**
     * 连接关闭，接收对端关闭&本端关闭
     * 
     * @param conn      WS连接
     * @param code      关闭代码（60000/60001表示本端主动关闭和握手关闭）
     */
    void onClose(WebSocket conn, int code);
    
    /**
     * 接收消息时异常
     * 
     * @param conn      WS连接
     * @param e         消息异常
     */
    void onException(WebSocket conn, Throwable e);
    
    /**
     * 发送消息时异常
     * 
     * @param conn      WS连接
     * @param e         消息异常
     * @param packet    消息包
     */
    void onExceptionSend(WebSocket conn, Throwable e, WebSocketPacket packet);

    /**
     * 接收到PING消息，框架会自动回PONG，业务侧无需回PONG，仅用于跟踪调试
     * 
     * @param conn      WS连接
     */
    void onPing(WebSocket conn);
    
    /**
     * 接收到PONG消息
     * 
     * @param conn      WS连接
     */
    void onPong(WebSocket conn);
    
    /**
     * 接收到文本消息
     * 
     * @param conn      WS连接
     * @param text      文本包
     */
    void onText(WebSocket conn, String text);
    
    /**
     * 接收到二进制包
     * 
     * @param conn      WS连接
     * @param binary    二进制包
     */
    void onBinary(WebSocket conn, byte[] binary);
    
    /**
     * 接收到中间包
     * 
     * @param conn      WS连接
     * @param middle    中间包字节数组
     */
    void onMiddle(WebSocket conn, byte[] middle);
    
    /**
     * 接收到自定义的其他消息
     * 
     * @param conn      WS连接
     * @param message   其他消息
     */
    void onOther(WebSocket conn, byte[] message);
}
